home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / qlib.exe / EMS.DOC < prev    next >
Encoding:
Text File  |  1991-11-29  |  6.6 KB  |  191 lines
  1. QLIB5 EMS.DOC expanded memory subroutines
  2. Copyright (C) 1991 Douglas Herr
  3. All rights reserved
  4.  
  5.  
  6. Expanded Memory subroutines take advantage of expanded memory conforming
  7. to the Lotus/Intel/Microsoft (LIM) Expanded Memory Specification (EMS).
  8. QLIB EMS subroutines allow your programs to store vast amounts of data in
  9. Expanded memory rather than creating temporary files on a disk.  A well-
  10. designed program using Expanded memory can be much faster than if Expanded
  11. memory isn't used.
  12.  
  13. Three primary versions of the EMS have been released: 3.0, 3.2 and 4.0.
  14. QLIB's EMS subroutines will work with all EMS versions.
  15.  
  16. EMS memory is allocated in "pages" of 16k bytes (actually 16,384 bytes)
  17. each.
  18.  
  19. Error codes returned by QLIB's EMS subroutines are:
  20.  
  21.      0 = no error
  22.      &H80 = memory manager software error - non-recoverable
  23.      &H81 = expanded memory hardware error - non-recoverable
  24.      &H83 = invalid EMS handle
  25.      &H85 = no available EMS handles
  26.      &H87 = not enough memory pages
  27.      &H88 = not enough memory pages available
  28.      &H89 = you tried to allocate zero pages
  29.  
  30.  
  31.  
  32.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  33.  
  34.      Subroutine: EMSclose(handle%, oops%)
  35.      object file: ems30.obj
  36.  
  37.         Closes an EMS "file" opened by EMSopen and releases the
  38.      associated expanded memory.  DOS will not release expanded memory
  39.      when the program ends, so you must use EMSclose for all open EMS
  40.      "files" before the program ends.
  41.  
  42.      Example:
  43.      CALL EMSclose(handle%, oops%)
  44.  
  45.  
  46.  
  47.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  48.  
  49.      Subroutine: EMSopen(pages%, handle%, oops%)
  50.      object file: ems30.obj
  51.  
  52.         "Opens" an EMS "file" for subsequent operations.  You specify
  53.      how many EMS pages you want (16k bytes, each page), and EMSopen
  54.      returns a handle to use in read/write operations. DOS will not
  55.      release expanded memory when the program ends, so you must use
  56.      QLIB's EMSclose for all "open" EMS "files" before the program ends.
  57.      A maximum of 4 EMS pages (64k bytes) may be allocated to each handle.
  58.  
  59.      Example:
  60.      CALL EMSopen(pages%, handle%,oops%)
  61.  
  62.  
  63.  
  64.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  65.  
  66.      Function: r% = EMSReady
  67.      object file: ems30.obj
  68.  
  69.         Determines if EMS memory is installed in the computer.  Returns
  70.      r% = -1 if EMS is installed, r% = 0 if not.
  71.  
  72.      Example:
  73.      REM $INCLUDE: 'qlib.bi'
  74.  
  75.      IF EMSReady THEN
  76.           PRINT "EMS is installed"
  77.           ELSE
  78.           PRINT "no EMS memory or driver not installed"
  79.      END IF
  80.  
  81.  
  82.  
  83.  
  84.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  85.  
  86.      Subroutine: EMSVersion(maj%, min%)
  87.      object file: ems30.obj
  88.  
  89.         Determines EMS version installed.  Use EMSReady to determine if
  90.      EMS memory is installed.
  91.  
  92.      Example:
  93.      CALL EMSVersion(maj%, min%)
  94.  
  95.  
  96.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  97.  
  98.      Subroutine: EMSSize(total%, free%)
  99.      object file: ems30.obj
  100.  
  101.         Determines the number of EMS memory pages available.  Use EMSReady
  102.      to determine if EMS memory is installed.
  103.  
  104.      Example:
  105.      CALL EMSSize(total%, free%)
  106.  
  107.  
  108.  
  109.  
  110.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  111.  
  112.      Subroutine: EMSread(handle%, aseg%, aptr%, emsptr%, bytes%, oops%)
  113.      object file: emsrw.obj
  114.  
  115.         Copies data from an EMS file opened by EMSopen to an array.
  116.      aseg% and aptr% are segment and offset pointers to the array, bytes%
  117.      is the number of bytes to be copied, and handle% is the handle returned
  118.      by EMSopen.  EMSptr% is the byte offset in the EMS "file" where you
  119.      want the read to start.  Note that EMSptr% = 0 at the start of the
  120.      "file".  If you want to read more than 32767 bytes from EMS memory
  121.      (up to 65,535), you should use a long integer bytes& instead of the
  122.      integer bytes%.
  123.  
  124.      Example:
  125.      CALL EMSread(handle, aseg%, aptr, emsptr%, bytes%, oops%)
  126.  
  127.  
  128.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  129.  
  130.      Subroutine: EMSwrite(handle%, aseg%, aptr%, emsptr%, bytes%, oops%)
  131.      object file: emsrw.obj
  132.  
  133.         Copies data from an array to an EMS file opened by EMSopen.
  134.      aseg% and aptr% are segment and offset pointers to the array, bytes%
  135.      is the number of bytes to be copied, and handle% is the handle returned
  136.      by EMSopen.  EMSptr% is the byte offset in the EMS "file" where you
  137.      want the write to start.  Note that EMSptr% = 0 at the start of the
  138.      "file".  If you want to read more than 32767 bytes from EMS memory
  139.      (up to 65,535), you should use a long integer bytes& instead of the
  140.      integer bytes%.
  141.  
  142.      Example:
  143.      CALL EMSwrite(handle, aseg%, aptr, emsptr%, bytes%, oops%))
  144.  
  145.  
  146.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  147.  
  148.      Subroutine: EMSRead1(handle%, value%, e%, oops%)
  149.      Subroutine: EMSRead2(handle%, value%, e%, oops%)
  150.      Subroutine: EMSRead4(handle%, value, e%, oops%)
  151.      Subroutine: EMSRead8(handle%, value, e%, oops%)
  152.      object file: emsrw1.obj
  153.  
  154.          EMSRead[n] subroutines copy a value from element e% of an array
  155.      stored in expanded memory.  In each case, Value is an n-byte number:
  156.      EMSRead1 is for QLIB's 1-byte short integers, EMSRead2 is for 2-byte
  157.      integers, EMSRead4 is for 4-byte long integers or single-precision real
  158.      numbers, EMSRead8 is for 8-byte double-precision real numbers or for
  159.      BC7's CURRENCY integers.  Oops% returned by EMSRead[n] is an EMS
  160.      error code.
  161.  
  162.          Since value's data type is ambiguous in EMSRead4 and EMSRead8,
  163.      be sure that you are using the data type you intended.
  164.  
  165.  
  166.      Example:
  167.      REM  A SINGLE array has been stored in expanded memory, but
  168.      REM  I need to see what the 18th element of the array is.
  169.      REM  The 18th element is e% = 17, since the first element is
  170.      REM  e% = 0
  171.  
  172.      e% = 17
  173.      CALL EMSRead4(handle%, value!, e%, oops%)
  174.      a$ = "The 18th element is" + STR$(value!)
  175.      PRINT a$
  176.  
  177.  
  178.  
  179.  
  180.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  181.  
  182.      Subroutine: EMSWrite1(handle%, value%, e%, oops%)
  183.      Subroutine: EMSWrite2(handle%, value%, e%, oops%)
  184.      Subroutine: EMSWrite4(handle%, value, e%, oops%)
  185.      Subroutine: EMSWrite8(handle%, value, e%, oops%)
  186.      object file: emsrw1.obj
  187.  
  188.          Replaces element e% of an array stored in expanded memory
  189.      with a value.  This subroutine is the complement of EMSRead[n].
  190.      See EMSRead[n] for example.
  191.